---
title: "Custom CSS for Spree Storefront"
sidebarTitle: "Custom CSS"
description: "Learn how to add custom CSS stylesheets to your Spree storefront"
---

Spree Storefront is built on top of [Tailwind CSS 4](https://tailwindcss.com/). After installing Spree you should find a main CSS file:

* [app/assets/tailwind/application.css](https://github.com/spree/spree/blob/main/storefront/lib/generators/spree/storefront/install/templates/application.css) - This is the main CSS file that imports Tailwind and adds storefront styles

If you're missing this file, or migrating from a previous version of Spree, you can generate it using the following command:

```bash
bin/rails g spree:storefront:install
```

<Info>
  Tailwind 4 uses a CSS-first configuration approach. There's no `tailwind.config.js` file - all configuration is done directly in CSS using the `@theme` directive.
</Info>

## Basic Structure

Your [application.css](https://github.com/spree/spree/blob/main/storefront/lib/generators/spree/storefront/install/templates/application.css) file should look something like this:

```css app/assets/tailwind/application.css
@import "tailwindcss";

@theme {
  /* Theme customizations go here */
}

/* Your custom styles */
```

## Importing Additional CSS Files

Create a new CSS file in the `app/assets/stylesheets` directory:

```bash
touch app/assets/tailwind/my_custom_styles.css
```

In the `my_custom_styles.css` file, add your styles:

```css
.my-custom-class {
  color: red;
}
```

Then import it in your `application.css` file:

```css app/assets/tailwind/application.css
@import "tailwindcss";
@import "my_custom_styles.css"; /* [!code ++] */
```

## Importing 3rd Party CSS Libraries

You can import a 3rd party CSS library directly from a CDN:

```css app/assets/tailwind/application.css
@import "tailwindcss";
@import url("https://esm.sh/swiper@11.2.2/swiper-bundle.min.css"); /* [!code ++] */
```

## CSS Variables

Spree Storefront uses CSS variables that are automatically injected into the page. This allows store owners to change colors, fonts, etc. from the admin dashboard via Page Builder.

The default variables look like this:

```css app/assets/tailwind/application.css
:root {
  --primary: #000000;
  --accent: #F0EFE9;
  --danger: #C73528;
  --success: #00C773;
  --neutral: #999999;

  --background: #FFFFFF;
  --text: #000000;

  --border-default-color: #E9E7DC;
  --border-default-width: 1px;
  --border-default-radius: 6px;

  --button: #000000;
  --button-rgb: 0, 0, 0;
  --button-text: #ffffff;
  --button-border-radius: 100px;
  --button-border-width: 1px;
  --button-border-color: ;

  --button-hover: #000000;
  --button-hover-text: #ffffff;

  --secondary-button: #FFFFFF;
  --secondary-button-text: #000000;
  --secondary-button-hover: #000000;
  --secondary-button-hover-text: #FFFFFF;

  --input: #E9E7DC;
  --input-bg: #ffffff;
  --input-text: #6b7280;
  --input-focus-bg: #ffffff;
  --input-border-radius: 8px;

  --neutral-50: #F3F3F3;
  --neutral-100: #EAEAEA;
  --neutral-200: #D4D4D4;
  --neutral-300: #B3B3B3;
  --neutral-400: #999999;
  --neutral-500: #808080;
  --neutral-600: #666666;
  --neutral-700: #4D4D4D;
  --neutral-800: #333333;
  --neutral-900: #1A1A1A;
  --accent-100: #FBFAF8;
}
```

They are defined in the [app/views/themes/default/spree/shared/_css_variables.html.erb](https://github.com/spree/spree/blob/main/storefront/app/views/themes/default/spree/shared/_css_variables.html.erb) file which should be present in your theme.

## Customizing with @theme

Tailwind 4 uses the `@theme` directive for customizations. You can extend or override the default theme:

```css app/assets/tailwind/application.css
@import "tailwindcss";

@theme {
  /* Add custom colors using Spree's CSS variables */
  --color-primary: var(--primary);
  --color-accent: var(--accent);
  --color-danger: var(--danger);
  --color-success: var(--success);

  /* Add custom fonts */
  --font-display: "Playfair Display", serif;

  /* Add custom spacing */
  --spacing-18: 4.5rem;

  /* Add custom border radius */
  --radius-button: var(--button-border-radius);
}
```

Then use them in your templates:

```erb
<div class="bg-primary text-white font-display p-18 rounded-button">
  Custom styled content
</div>
```

## Overriding Section Styles

Each section has CSS classes you can target to customize its appearance:

```css
/* Section container classes follow the pattern: section-{section-type} */
.section-image-with-text {
  /* Custom styles for Image with Text section */
}

.section-featured-taxon {
  /* Custom styles for Featured Taxon section */
}

/* Block-specific styles within sections */
.image-with-text--heading {
  font-family: serif;
}

.rich-text--text {
  line-height: 1.8;
}
```

## Using Tailwind Utility Classes

You can use Tailwind utility classes directly in your templates:

```erb
<div class="flex items-center gap-4 p-6 bg-accent rounded-lg">
  <%= product.name %>
</div>
```

### Arbitrary Values

Tailwind 4 supports arbitrary values for one-off customizations:

```erb
<div class="p-[17px] bg-[#1a1a1a] text-[13px] grid-cols-[1fr_2fr]">
  Custom values
</div>
```

### Variant Modifiers

Use variant modifiers for responsive and state-based styles:

```erb
<div class="p-4 md:p-6 lg:p-8 hover:bg-accent active:scale-95">
  Responsive and interactive
</div>
```

## Adding Custom Utilities

You can add custom utilities using standard CSS with the `@utility` directive:

```css
@import "tailwindcss";

@utility content-auto {
  content-visibility: auto;
}

@utility scrollbar-hidden {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}
```

Then use them like any other utility:

```erb
<div class="content-auto scrollbar-hidden">
  <!-- Content -->
</div>
```

## Adding Custom Variants

Create custom variants with the `@variant` directive:

```css
@import "tailwindcss";

@variant pointer-coarse (@media (pointer: coarse));
@variant theme-dark (&:where([data-theme="dark"], [data-theme="dark"] *));
```

Use them in your templates:

```erb
<button class="p-2 pointer-coarse:p-4 theme-dark:bg-gray-800">
  Touch-friendly button
</button>
```

## Related Documentation

- [Themes](/developer/storefront/themes) - Theme settings and colors
- [Custom JavaScript](/developer/storefront/custom-javascript) - Adding interactivity
- [Tailwind CSS 4 Documentation](https://tailwindcss.com/docs) - Official Tailwind docs
